aws4
A small utility to sign vanilla Node.js http(s) request options using Amazon's
AWS Signature Version 4.
If you want to sign and send AWS requests in a browser, or an environment like Cloudflare Workers, then check out aws4fetch – otherwise you can also bundle this library for use in older browsers.
The only AWS service that doesn't support v4 as of 2020-05-22 is
SimpleDB
(it only supports AWS Signature Version 2).
It also provides defaults for a number of core AWS headers and
request parameters, making it very easy to query AWS services, or
build out a fully-featured AWS library.
Example
var https = require('https')
var aws4 = require('aws4')
function request(opts) { https.request(opts, function(res) { res.pipe(process.stdout) }).end(opts.body || '') }
var opts = { host: 'my-bucket.s3.us-west-1.amazonaws.com', path: '/my-object', service: 's3', region: 'us-west-1' }
aws4.sign(opts, { accessKeyId: '', secretAccessKey: '' })
aws4.sign(opts)
opts = { host: 'my-bucket.s3.us-west-1.amazonaws.com', path: '/my-object' }
opts = { host: 'my-bucket.s3.amazonaws.com', path: '/?X-Amz-Expires=12345', signQuery: true }
opts = { service: 'sqs', region: 'us-east-1', path: '/?Action=ListQueues' }
opts = { service: 'sqs', path: '/?Action=ListQueues' }
aws4.sign(opts)
console.log(opts)
request(opts)
request(aws4.sign({ service: 'iam', body: 'Action=ListGroups&Version=2010-05-08' }))
request(aws4.sign({
service: 'dynamodb',
region: 'ap-southeast-2',
method: 'POST',
path: '/',
headers: {
'Content-Type': 'application/x-amz-json-1.0',
'X-Amz-Target': 'DynamoDB_20120810.ListTables'
},
body: '{}'
}))
request(aws4.sign({
host: '07tjusf2h91cunochc.us-east-1.aoss.amazonaws.com',
method: 'PUT',
path: '/my-index',
body: '{"mappings":{}}',
headers: {
'Content-Type': 'application/json',
'X-Amz-Content-Sha256': 'UNSIGNED-PAYLOAD'
},
extraHeadersToIgnore: {
'content-length': true
}
}))
request(aws4.sign({
service: 'mycustomservice',
path: '/whatever',
headers: {
'Range': 'bytes=200-1000, 2000-6576, 19000-'
},
extraHeadersToInclude: {
'range': true
}
}))
var signer = new aws4.RequestSigner({
service: 'codecommit',
host: 'git-codecommit.us-east-1.amazonaws.com',
method: 'GIT',
path: '/v1/repos/MyAwesomeRepo',
})
var password = signer.getDateTime() + 'Z' + signer.signature()
API
aws4.sign(requestOptions, [credentials])
Calculates and populates any necessary AWS headers and/or request
options on requestOptions
. Returns requestOptions
as a convenience for chaining.
requestOptions
is an object holding the same options that the Node.js
http.request
function takes.
The following properties of requestOptions
are used in the signing or
populated if they don't already exist:
hostname
or host
(will try to be determined from service
and region
if not given)method
(will use 'GET'
if not given or 'POST'
if there is a body
)path
(will use '/'
if not given)body
(will use ''
if not given)service
(will try to be calculated from hostname
or host
if not given)region
(will try to be calculated from hostname
or host
or use 'us-east-1'
if not given)signQuery
(to sign the query instead of adding an Authorization
header, defaults to false)extraHeadersToIgnore
(an object with lowercase header keys to ignore when signing, eg { 'content-length': true }
)extraHeadersToInclude
(an object with lowercase header keys to include when signing, overriding any ignores)headers['Host']
(will use hostname
or host
or be calculated if not given)headers['Content-Type']
(will use 'application/x-www-form-urlencoded; charset=utf-8'
if not given and there is a body
)headers['Date']
(used to calculate the signature date if given, otherwise new Date
is used)
Your AWS credentials (which can be found in your
AWS console)
can be specified in one of two ways:
- As the second argument, like this:
aws4.sign(requestOptions, {
secretAccessKey: "<your-secret-access-key>",
accessKeyId: "<your-access-key-id>",
sessionToken: "<your-session-token>"
})
- From
process.env
, such as this:
export AWS_ACCESS_KEY_ID="<your-access-key-id>"
export AWS_SECRET_ACCESS_KEY="<your-secret-access-key>"
export AWS_SESSION_TOKEN="<your-session-token>"
(will also use AWS_ACCESS_KEY
and AWS_SECRET_KEY
if available)
The sessionToken
property and AWS_SESSION_TOKEN
environment variable are optional for signing
with IAM STS temporary credentials.
Installation
With npm do:
npm install aws4
Can also be used in the browser.
Thanks
Thanks to @jed for his
dynamo-client lib where I first
committed and subsequently extracted this code.
Also thanks to the
official Node.js AWS SDK for giving
me a start on implementing the v4 signature.